|
|
Home /
Products /
Numerical Libraries / NAG Toolbox for MATLAB®
Calling NAG Routines From MATLAB®
Although the NAG Library is written in Fortran, you can use it from
within MATLAB as if it were a collection of native MATLAB commands.
The code in the toolbox will transform your MATLAB data into a form
suitable for passing to Fortran, and will transform the results into
MATLAB objects on successful completion of the algorithm.
Here is an example of how to use the NAG Library to compute the
solution of a real system of linear equations, AX=B, where A is an
n by n matrix and X and B are n vectors.
a = [ 1.80, 2.88, 2.05, -0.89;
5.25, -2.95, -0.95, -3.80;
1.58, -2.69, -2.90, -1.04;
-1.11, -0.66, -0.59, 0.80];
b = [ 9.52;
24.35;
0.77;
-6.22];
[aOut, ipiv, bOut, info] = f07aa(a, b);
bOut
bOut =
1.0000
-1.0000
3.0000
-5.0000
Here we see that the NAG routine f07aa takes two arguments,
the matrix of coefficients, A, and the vector representing the
right-hand side, B (actually, since f07aa can handle multiple
right-hand sides, B is really a matrix). It returns four results as
follows:
- aOut
- the LU factorisation of A
- ipiv
- the pivot indices that describe the permutation matrix used to
compute the result
- bOut
- the solution matrix
- info
- a diagnostic parameter that indicates whether the algorithm was
successful or not
Since info=0 we know that the algorithm succeeded. Had it been
non-zero a warning would have been printed (see Errors and Warnings).
An example of the use of each NAG routine in MATLAB is provided in
the individual routine documents.
Optional Arguments
Many NAG routines have optional parameters. In these cases the
routine will either infer a suitable value from the other inputs, or
provide a default that is acceptable in most situations. A very
common case is where the underlying Fortran routine requires the user
to provide parameters which describe the size of a matrix, which can
easily be inferred in MATLAB. For example, in the system of equations
given in the previous section, it is obvious
that the rank, n, of the matrix A is 4. However we can tell
MATLAB that the rank is 3, in which case it will solve the system
represented by the top-left 3x3 section of A, and the first three
elements of B (see the section on Types for an
explanation of the use of the int32 command here):
[aOut, ipiv, bOut, info] = f07aa(a, b, 'n', int32(3));
bOut
bOut =
4.1631
-2.1249
3.9737
-6.2200
The last element of bOut can be ignored. Since b was a 4x1 matrix on
input, it will be a 4x1 matrix on output, even though the last element
is not being used. A similar outcome can be achieved by:
[aOut, ipiv, bOut, info] = f07aa(a(1:3,1:3), b(1:3));
bOut
bOut =
4.1631
-2.1249
3.9737
To summarise:
- optional parameters are provided after all compulsory
parameters;
- optional parameters are provided in pairs: a string representing
the name of the parameter followed by its value;
- optional parameters can be provided in any order.
Another common use of optional parameters is to over-ride default
values. For example, g01hb computes probabilities associated with a
multivariate distribution to a relative accuracy which defaults to
0.0001:
tail = 'c';
a = [-2; -2; -2; -2];
b = [2; 2; 2; 2];
xmu = [0; 0; 0; 0];
sig = [1.0, 0.9, 0.9, 0.9;
0.9, 1.0, 0.9, 0.9;
0.9, 0.9, 1.0, 0.9;
0.9, 0.9, 0.9, 1.0];
g01hb(tail, a, b, xmu, sig)
ans =
0.9142
We can request more or less accuracy by varying the parameter tol:
g01hb(tail, a, b, xmu, sig,'tol',0.1)
ans =
0.9182
Finally, we note that some NAG routines use a different mechanism for
setting options, which involves calling an initialisation routine, a
separate option setting routine, and then a computational routine.
For an example of this see f12fe.
The NAG routines can throw a number of errors. The names of those
errors and the circumstances under which they are likely to be
encountered are as follows:
- NAG:licenceError
- A valid licence for this product could not be found.
- NAG:arrayBoundError
- An array provided to the routine is too small.
- NAG:callBackError
- An error occurred when executing an M-File passed as a parameter
to the routine.
- NAG:missingInputParameters
- At least one compulsory input parameter is missing.
- NAG:optionalParameterError
- Either the optional parameters are not in name/value pairs, or the
name provided does not correspond to an optional parameter. Note that
this error can arise if some compulsory parameters have been
omitted.
- NAG:tooManyOutputParameters
- The user has requested too many output parameters.
- NAG:typeError
- A parameter provided to the routine or returned from an M-File
called by the routine is of the wrong type. See the section on Types for more details.
- NAG:valueError
- An incorrect value has been provided for a parameter.
In most cases the error message will give more precise details of how
the error was triggered. For example a NAG:arrayBoundError might
display the message:
??? The dimension of parameter 2 (A) should be at least 4
The NAG routines can also throw two kinds of warnings:
- NAG:truncationWarning
- A string was truncated when copying the contents of a cell array
of strings into a Fortran data structure.
- NAG:warning
- The NAG routine returned an error or warning.
The latter is important, and means that on exit the value of the
parameter ifail (or, in chapters f07 and f08, info) was non-zero on
exit. For details about how to interpret this value the user should
consult the relevant routine document.
If the user does not wish to see a warning then they can disable it in
the usual way, for example:
warning('off', 'NAG:warning')
In this case it is vital that the user checks the value of
ifail or info on exit from the routine.
The interfaces to NAG routines in this toolbox are quite precise about
the types of their parameters. Since MATLAB assumes by default that
every number is a double unless otherwise stated, this means that
users need to coerce their input to the appropriate type if it is an
integer, a complex number or a boolean. Similarly, in M-Files called
by the NAG routine, the user must ensure that the results returned are
of the appropriate type. This is to ensure the correct alignment
between the MATLAB and Fortran types.
Typically the user will call
int32 to create an
integer, complex to create a complex number, and logical to create a boolean. There are numerous
examples in the routine documents. If an object of the incorrect type
is provided then a NAG:typeError will be thrown:
s01ea(0)
??? Parameter number 1 is not a complex scalar of class double.
Providing M-Files as Arguments
Many NAG routines expect the user to provide an M-File to evaluate a
function, which might represent an integrand, the objective function
in an optimization problem etc. Here is an example showing how to
solve an integral:
d01ah(0, 1, 1e-5, 'd01ah_f', int32(0))
ans =
3.1416
The integrand is contained in the file 'd01ah_f.m', which looks like:
function [result] = d01ah_f(x)
result=4.0/(1.0+x^2);
The user should consult the MATLAB documentation on Working
with M-Files and Editing and Debugging M-Files
for general advice. For every instance where a NAG routine expects an
M-File to be provided, an example is given.
Support From NAG
NAG Response Centres
The NAG Response Centres are available for general enquiries from all users and
also for technical queries from users with support. The Response Centres are
open during office hours, but contact is possible by fax, email and telephone
(answering machine) at all times. Please see the NAG web
site for contact details. When contacting one of the NAG Response Centres, it
helps us to deal with your query quickly if you can quote your NAG user
reference and NAG product code.
NAG Web Site
The NAG web site is an information service providing items of interest to users
and prospective users of NAG products and services. The information is
regularly updated and reviewed, and includes implementation availability,
descriptions of products, down-loadable software, case studies, industry
articles and technical reports. The NAG web site can be accessed via:
|
